<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>7 - Keyboard and Display Controls</title>
<link rev= "made" href= "mailto:www@openbsd.org">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name= "resource-type" content= "document">
<meta name= "description"   content= "the OpenBSD FAQ page">
<meta name= "keywords"      content= "openbsd,faq">
<meta name= "distribution"  content= "global">
<meta name= "copyright"     content= "This document copyright 1998-2008 by OpenBSD.">
</head>

<!-- Passes validator.w3.org, please keep it this way;
please, use a max of 72 chars per line -->

<body bgcolor= "#ffffff" text= "#000000">

<a href="../index.html">
<img alt="[OpenBSD]" height=30 width=141 src="../images/smalltitle.gif" border="0">    
</a>
<p>
<font color= "#0000e0">
<a href= "index.html">[FAQ Index]</a>
<a href= "faq6.html">[To Section 6 - Networking]</a>
<a href= "faq8.html">[To Section 8 - General Questions]</a>
</font>

<h1><font color="#e00000">7 - Keyboard and Display Controls</font></h1>
<hr>
<p>
<h3>Table of Contents</h3>
<ul>
<li><a href= "#Keyboard"     >7.1 - How do I remap the keyboard? (wscons)</a>
<li><a href= "#ConsoleMouse" >7.2 - Is there console mouse support in OpenBSD?</a>
<li><a href= "#ConsoleClear" >7.3 - How do I clear the console each time
    a user logs out?</a>
<li><a href= "#Scrollback"   >7.4 - Accessing the console scrollback
    buffer. (amd64, i386, some Alpha)</a>
<li><a href= "#SwitchConsole">7.5 - How do I switch consoles? (amd64, i386,
    Zaurus, some Alpha)</a>
<li><a href= "#80x50"        >7.6 - How can I use a console resolution 
    of 80x50? (amd64, i386, some Alpha)</a>
<li><a href= "#SerCon"       >7.7 - How do I use a serial console?</a>
<li><a href= "#Blanker"      >7.8 - How do I blank my console? (wscons)</a>
<li><a href= "#ALLCAPS"      >7.9 - EVERYTHING I TYPE AT THE LOGIN IS
    IN CAPS!</a>
</ul>
<hr>

<br>
<p>
<a name= "Keyboard"></a>
<h2>7.1 - How do I remap the keyboard? <i>(wscons)</i></h2>

<p>
The ports that use the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wscons&amp;sektion=4">wscons(4)</a>
console driver: <a href="../alpha.html">alpha</a>, 
<a href="../amd64.html">amd64</a>,
<a href="../hppa.html">hppa</a>,
<a href="../i386.html">i386</a>,
<a href="../mac68k.html">mac68k</a>,
<a href="../macppc.html">macppc</a>,
<a href="../sparc.html">sparc</a>,
<a href="../sparc64.html">sparc64</a>,
<a href="../vax.html">vax</a>,
and <a href="../zaurus.html">zaurus</a>.

<p>
With wscons(4) consoles, most options can be controlled using the 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wsconsctl&amp;sektion=8">wsconsctl(8)</a>
utility. For example, to change keymappings with
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wsconsctl&amp;sektion=8">wsconsctl(8)</a> 
one would execute the following:

<blockquote><pre>
# <strong>wsconsctl -w keyboard.encoding=uk</strong>
</pre></blockquote>

<p>
In the next example, we will remap &quot;Caps Lock&quot; to be
&quot;Control L&quot;:

<blockquote><pre>
# <strong>wsconsctl -w keyboard.map+="keysym Caps_Lock = Control_L"</strong>
</pre></blockquote>


<a name= "ConsoleMouse"></a>
<h2>7.2 - Is there console mouse support in OpenBSD?</h2>

<p>
For the <a href="../alpha.html">alpha</a>,
<a href="../amd64.html">amd64</a>
 and <a href="../i386.html">i386</a> 
platforms, OpenBSD provides 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wsmoused&amp;sektion=8&amp;arch=i386">wsmoused(8)</a>,
a port of FreeBSD's moused(8).  It can be enabled automatically 
at startup by editing the appropriate line in 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=rc.conf&amp;sektion=8">rc.conf(8)</a>. 

<p>
<a name= "ConsoleClear"></a>
<h2>7.3 - Clearing the console each time a user logs out.</h2>

<p>
To do this you must add a line in 
<kbd><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=gettytab&amp;sektion=5">/etc/gettytab(5)</a></kbd>.
Change the current section:

<blockquote><pre>
P|Pc|Pc console:\
        :np:sp#9600:
</pre></blockquote>

<p>
adding the line &quot;<tt>:cl=\E[H\E[2J:</tt>&quot; at the end, so that
it ends up looking like this:

<blockquote><pre>
P|Pc|Pc console:\
        :np:sp#9600:\
	:cl=\E[H\E[2J:
</pre></blockquote>

<p>
<a name= "Scrollback"></a>
<h2>7.4 - Accessing the Console Scrollback Buffer 
  <i>(amd64, i386, some Alpha)</i></h2>

<p>
On some platforms,
OpenBSD provides a console scrollback buffer. This allows you 
to see information that has already scrolled past your screen. 
To move up and down in the buffer, simply use the key combinations
<tt>[SHIFT]+[PGUP]</tt> and <tt>[SHIFT]+[PGDN]</tt>.

<p>
The default scrollback buffer, or the number of pages that you can 
move up and view, is 8.
This is a feature of the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=vga&amp;sektion=4">vga(4)</a>
driver, so it will not work without a VGA card on any platform (many
Alpha systems have TGA video).

<p>
Due to space limitations, the install kernels do not provide the 
scrollback function.
<a href="#SwitchConsole">Switching consoles</a> will clear the 
scrollback buffer.

<p>
<a name= "SwitchConsole"></a>
<h2>7.5 - How do I switch consoles? <i>(amd64, i386, Zaurus,
some Alpha)</i></h2>

On amd64, i386 and Alpha systems with 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=vga&amp;sektion=4">vga(4)</a>
cards, OpenBSD provides six virtual terminals by default,
/dev/ttyC0 through /dev/ttyC5.
ttyC4 is reserved for use by the X Window system, leaving five
text consoles.
You can switch between them using
<tt>[CTRL]+[ALT]+[F1]</tt>, <tt>[CTRL]+[ALT]+[F2]</tt>,
<tt>[CTRL]+[ALT]+[F3]</tt>, <tt>[CTRL]+[ALT]+[F4]</tt> and
<tt>[CTRL]+[ALT]+[F6]</tt>.

<p>
The X environment uses ttyC4, <tt>[CTRL]+[ALT]+[F5]</tt>.
When using X,
the <tt>[CTRL]+[ALT]+[F</tt><i>n</i><tt>]</tt> keys will take you to
the text screens;
<tt>[CTRL]+[ALT]+[F5]</tt>
will take you back to the graphical environment.

<p>
If you wish to have more than the default number of virtual consoles,
use the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wsconscfg&amp;sektion=8">wsconscfg(8)</a>
command to create screens for ttyC6, ttyC7 and above.
For example:

<blockquote>
<pre>
wsconscfg -t 80x25 6
</pre>
</blockquote>

will create a virtual terminal for ttyC6,
accessed by <tt>[CTRL]+[ALT]+[F7]</tt>.
Don't forget to add this command to your
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=rc.local&amp;sektion=8"><tt>rc.local(8)</tt></a>
file if you want the extra screen the next time you boot the computer.

<p>
Note that you will not get a "<tt>login:</tt>" prompt
on the newly-created virtual console unless you set it to "on" in 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=ttys&amp;sektion=5"><tt>/etc/ttys(5)</tt></a>,
and either reboot or send
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=init&amp;sektion=8">init(8)</a>
a HUP signal using 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=kill&amp;sektion=1">kill(1)</a>.

<p>
On the Zaurus, two virtual terminals (/dev/ttyC0 and /dev/ttyC1)
are available by default, accessible with <tt>[ALT]+[CALENDAR]</tt>
and <tt>[ALT]+[ADDRESS]</tt> (The <tt>[ALT]</tt> key is the one
right of the left <tt>[CTRL]</tt> key).

<a name="80x50"></a>
<h2>7.6 - How do I use a console resolution of 80x50? <i>(amd64, i386,
some Alpha)</i></h2>

amd64, i386, and VGA Alpha users normally get a console screen of 25
lines of 80 characters.
However, many VGA video cards are capable of displaying a higher
text resolution of 50 lines of 80 characters.  

<p>
First, a font that supports the desired resolution must be loaded using
the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wsfontload&amp;sektion=8">wsfontload(8)</a>
command.  The standard 80x25 text screen uses 8x16 pixel fonts;
to double the number of lines we will have to use 8x8 pixel fonts.

<p>
After that, we will have to delete and recreate a 
<a href="#SwitchConsole">virtual console</a> at the desired screen 
resolution, using the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wsconscfg&amp;sektion=8">wsconscfg(8)</a>
command.

<p>
This can be done automatically at boot by adding the following lines to
the end of your 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=rc.local&amp;sektion=8"><tt>rc.local(8)</tt></a>
file:
<blockquote>
<pre>
wsfontload -h 8 -e ibm /usr/share/misc/pcvtfonts/vt220l.808
wsconscfg -dF 5
wsconscfg -t 80x50 5
</pre>
</blockquote>

As with any modification to your system configuration, it is
recommended you spend some time with the man pages to understand what
these commands do.

<p>
The first line above loads the 8x8 font.  The second line deletes screen
5 (which would be accessed by <tt>[CTRL]+[ALT]+[F6]</tt>).  The third
line creates a new screen 5 with 50 lines of 80
characters each.  If you do this, you will see your primary screen, and
the other three default virtual consoles, come up in the standard 80x25
mode, but a new screen 5 at 80x50 accessible through <tt>[CTRL]+[ALT]+[F6]</tt>.

<p>
Remember that <tt>[CTRL]+[ALT]+[F1]</tt> is screen 0 (ttyC0).
If you wish to alter other screens,
simply repeat the delete and add screen steps
for whichever screens you want running at the 80x50 resolution.

<p>
You should avoid changing screen 4 (ttyC4, <tt>[CTRL]+[ALT]+[F5]</tt>),
which is used by X as a graphical screen.  It is also not possible to 
change the resolution of the primary console device (i.e., ttyC0).

<p>
As one might expect, all these commands can also be entered at the
command prompt, as root, or (better) using
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=sudo&amp;sektion=8">sudo(8)</a>.

<p>
<b>Note: this will not work on all video cards.</b>  Unfortunately, not
all video cards support the uploaded fonts that
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wscons&amp;sektion=4">wscons(4)</a>
requires to achieve the 80x50 text mode.  In these cases, you might wish
to consider running X.


<a name="SerCon"></a>
<h2>7.7 - How do I use a serial console?</h2>

There are many reasons you may wish to use a serial console for your 
OpenBSD system:
<ul>
<li>Recording console output (for documentation). 
<li>Remote management.
<li>Easier maintenance of a large quantity of machines
<li>Providing a useful dmesg from machines which might otherwise be
  difficult to get one from.
<li>Providing an accurate "trace" and "ps" output if your system
  crashes so developers can have a chance to fix the problem.
</ul>
OpenBSD supports serial console on most platforms, however details
vary greatly between platforms.

<p>
Note that serial interfacing is NOT a trivial task -- you will often
need unusual cables, and ports are not standardized between machines, in
some cases, not even consistent on one machine.  It is assumed you know
how to select the appropriate cable to go between your computer and the
device acting as your serial terminal. A full tutorial on serial
interfacing is beyond the scope of this article, however, we offer one
hint: just because the ends plug in doesn't mean it will work.

<a name="SerContty"></a>
<h3><i>/etc/ttys</i> change</h3>
There are two parts to getting a functional serial console on an OpenBSD
system.  First, you must have OpenBSD use your serial port as a
console for status and single user mode.  This part is very platform
dependent.  Second, you must enable the serial port to be used as an
interactive terminal, so a user can log into it when running multi-user.
This part is fairly similar between platforms, and is detailed here.

<p>
Terminal sessions are controlled by the 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=ttys&amp;sektion=5"><i>/etc/ttys</i></a>
file.  Before OpenBSD will give you a "<tt>login:</tt>" prompt at a
device, it has to be enabled in <i>/etc/ttys</i>, after all, there are
other uses for a serial port other than for a terminal.  In platforms
which typically have an attached keyboard and screen as a console, the
serial terminal is typically disabled by default. We'll use the i386
platform as an example.  In this case, you must edit the line that
reads:

<pre>
     tty00   "/usr/libexec/getty std.9600"   unknown off
</pre>
to read something like:
<pre>
     tty00   "/usr/libexec/getty std.9600"   vt220   on secure
</pre>

Here, <tt>tty00</tt> is the serial port we are using as a console.
<tt>vt220</tt> is the 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=termcap&amp;sektion=5">termcap(5)</a>
entry that matches YOUR terminal (other likely options might include
<tt>vt100</tt>, <tt>xterm</tt>, etc.).
The "<tt>on</tt>" activates the 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=getty&amp;sektion=8"><i>getty</i></a>
for that serial port so that a "<tt>login:</tt>" prompt will be
presented, the "<tt>secure</tt>" permits a root (uid 0) login at this
console (which may or may not be what you desire), and the
"<tt>9600</tt>" is the terminal baud rate.
Resist the urge to crank the baud rate up to the maximum your hardware
can support, as you are more likely to create problems than benefit.
Most systems have a "default" speed (supported by default by the boot
ROM and/or the boot loader, often 9600), use this unless you have real
reason to use something different.

<p>
Note that you can use a
serial console for install without doing this step, as the system is
running in single user mode, and not using <i>getty</i> for login.

<p>
On some platforms and some configurations, you must bring the system up
in single user mode to make this change if a serial console is all you
have available.

<h3>amd64 and i386</h3>
To direct the boot process to use the serial port as a console, 
create or edit your 
<i><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=boot.conf&amp;sektion=8&amp;arch=i386">/etc/boot.conf</a></i>
file to include the line:
<pre>
     set tty com0
</pre>

to use the first serial port as your console.  The
default baud rate is 9600bps, this can be changed with a
<i>/etc/boot.conf</i> line using the stty option.  This file is put on
your boot drive, which could also be your install floppy, or the command
can be entered at the <tt>boot></tt> prompt from the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=boot&amp;sektion=8&amp;arch=i386">OpenBSD
second-stage boot loader</a> for a one-time (or first time) serial
console usage.


<p>
<h4>amd64 and i386 notes:</h4>
<ul>
<li>OpenBSD numbers the serial ports starting at <i>tty00</i>,
DOS/Windows labels them starting at <i>COM1</i>.  So, keep in mind
<i>tty02</i> is <i>COM3</i>, not <i>COM2</i>

<li>Some systems may be able to operate without a video card in the
machine, but certainly not all -- many systems consider this an error
condition.  Some machines will even refuse to work easily without a
keyboard attached.

<li>Some systems are capable of redirecting all BIOS keyboard and screen
activity to a serial port through a configuration option, so the machine
can be completely maintained through the serial port.
Your results may vary -- when using this feature, some BIOSs may prevent
the bootloader from seeing the serial port, and thus, the kernel will
not be told to use it.
Some BIOSs have an option to "Continue Console Redirection after POST"
(Power On Self Test), this should be set to "OFF", so the boot loader
and the kernel can handle their own console.
Unfortunately, this feature is not universal.

<li>PC compatible computers are not designed to be run from a serial
console, unlike some other platforms.  Even those systems that support a
serial console usually have it as a BIOS configuration option -- and
should the configuration information get corrupted, you will find the
system looking for a standard monitor and keyboard again.  You generally
must have some way to get a monitor and keyboard to your amd64 and i386 
systems in an emergency.

<li>You will need to edit <i>/etc/ttys</i> as 
<a href="#SerContty">above</a>.

</ul>


<h3>SPARC and UltraSPARC</h3>
These machines are designed to be completely maintainable with a serial
console.  Simply remove the keyboard from the machine, and the system
will run serial.

<h4>SPARC and UltraSPARC notes</h4>
<ul>
<li>The serial ports on a SPARC are labeled <i>ttya</i>,
<i>ttyb</i>, etc.

<li>Unlike some other platforms, it is not necessary to make any
changes to <i>/etc/ttys</i> to use a serial console.

<li>The SPARC/UltraSPARC systems interpret a BREAK signal on the console
port to be the same as a STOP-A command, and kicks the system back to
the Forth prompt, stopping any application and operating system at that
point.  This is handy when desired, but unfortunately, some serial
terminals at power-down and some RS-232 switching devices send something
the computer interprets as a break signal, halting the machine.  Test
before you go into production.

<li>If you have a keyboard and monitor attached, you can still force 
the serial console to be used instead by using the following commands 
at the <tt>ok</tt> prompt:
 <pre>
     ok <b>setenv input-device ttya</b>
     ok <b>setenv output-device ttya</b>
     ok <b>reset</b>
 </pre>
If the keyboard and monitor (ttyC0) are active in <i>/etc/ttys</i>
(<a href="#SerContty">above</a>), you can use the keyboard and monitor
in X.
</ul>

<h3>MacPPC</h3>
The MacPPC machines are configured for a serial console through
OpenFirmware.  Use the commands:
 <pre>
     ok <b>setenv output-device scca</b>
     ok <b>setenv input-device scca</b>
     ok <b>reset-all</b>
 </pre>
Set your serial console to 57600bps, 8N1.

<h4>MacPPC notes</h4>
<ul>
<li>Unfortunately, serial console is not directly possible on most
MacPPCs.  While most of these machines do have serial hardware, it isn't
accessible outside the machine.  Fortunately, a few companies offer
add-on devices for several Macintosh models which will make this port
available for use as a serial console (or other uses).  Use your
favorite search engine and look for "Macintosh internal serial port".

<li>You will have to change <tt>tty00</tt> in <i>/etc/ttys</i> to
<tt>on</tt> and set the speed to 57600 instead of the default of 9600 as
detailed <a href="#SerContty">above</a> in single user mode before
booting multi-user and having the serial console functional.  </ul>


<h3>Mac68k</h3>
Serial console is selected in the <i>Booter</i> program, under the
"<tt>Options</tt>" pull-down menu, then "<tt>Serial Ports</tt>".  Check
the "Serial Console" button, then choose the Modem or Printer port.  You
will need a Macintosh modem or printer cable to attach to the Mac's
serial ports.  If you wish to have this as default, tell the Booter
program to save your options.


<h4>Mac68k Notes</h4>
<ul>
<li>The modem port is <i>tty00</i>, the printer port is <i>tty01</i>.

<li>The Mac68k doesn't turn on its serial port until called upon, so
your breakout box may not show any signals on the Mac's serial port
until the OpenBSD boot process has started.

<li>You will have to enable the port (<i>tty00</i> or <i>tty01</i>) as
indicated <a href="#SerContty">above</a>.  </ul>

<a name="Blanker"></a>
<h2>7.8 - How do I blank my console? (wscons)</h2>
If you wish to blank your console after a period of inactivity without
using X, you can alter the following
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wscons&amp;sektion=4">wscons(4)</a>
variables:

<ul>
<li><b><tt>display.vblank</tt></b> set to <tt>on</tt> will disable the
vertical sync pulse, which will cause many monitors to go into an
"energy saver" mode.  This will require more time to bring the screen
back on, but will reduce energy consumption and heat production of newer
monitors.  When set to <tt>off</tt>, the display will blank, but the
monitor will still be receiving the normal horizontal and vertical sync
pulses, so the unblanking will be almost instant.

<li><b><tt>display.screen_off</tt></b> determines the blanking time in
thousandths of a second, i.e., 60000 would set the timeout to one
minute.

<li><b><tt>display.kbdact</tt></b> determines if keyboard activity will
restore the blanked screen.  Usually, this is desirable.

<li><b><tt>display.outact</tt></b> determines if screen output will
restore the blanked screen.
</ul>

You can set these variables at the command line using the 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wsconsctl&amp;sektion=8">wsconsctl(8)</a> 
command:
<pre>
     # <b>wsconsctl -w display.screen_off=60000</b>
     display.screen_off -> 60000
</pre>

or set them permanently by editing 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=wsconsctl.conf&amp;sektion=5"><i>/etc/wsconsctl.conf</i></a>
so these changes take place at next boot:

<pre>
     display.vblank=on               # enable vertical sync blank
     display.screen_off=600000       # set screen blank timeout to 10 minutes
     display.kbdact=on               # Restore screen on keyboard input
     display.outact=off              # Restore screen on display output
</pre>

The blanker is activated when either <tt>display.kbdact</tt> or
<tt>display.outact</tt> is set to "<tt>on</tt>".  

<a name="ALLCAPS"></a>
<h2>7.9 - EVERYTHING I TYPE AT THE LOGIN PROMPT IS IN CAPS!</H2>
This is a feature, not a bug, actually.

<p>
Virtually all Unix commands and user names are entered using all
lowercase.
However, some very old terminals were only capable of uppercase
characters, making them difficult, if not impossible, to use with Unix.
As a workaround, if you entered your user name in all uppercase,
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=getty&amp;sektion=8">getty(8)</a>
would assume your terminal was "lowercase challenged", and simply
interpret everything you type as lowercase, while echoing it as
uppercase.
If you have a mixed-case or uppercase password, this will make login
impossible.

<p>
Hitting CTRL-D at the login prompt will cause getty(8) to terminate, and
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=init&amp;sektion=8">init(8)</a>
will relaunch a new one, which will accept uppercase and lowercase
properly.

<p>
<font color= "#0000e0">
<a href= "index.html">[FAQ Index]</a>
<a href= "faq6.html">[To Section 6 - Networking]</a>
<a href= "faq8.html">[To Section 8 - General Questions]</a>
</font>

<p>
<hr>
<a href= "index.html"><img height= "24" width= "24" src= "../images/back.gif" border= "0" alt= "[back]"></a> 
<a href= "mailto:www@openbsd.org">www@openbsd.org</a>
<br>
<small>$OpenBSD: faq7.html,v 1.78 2008/03/01 11:31:08 steven Exp $</small>
</body>
</html>
